# 12 - 关键设计模式

## 贯穿项目的设计思想总结

---

## 1. 安全第一 (Security by Default)

**失败关闭**是整个项目最核心的设计原则。

```
默认值:
  isConcurrencySafe() → false     （假设不安全）
  isReadOnly() → false             （假设会写入）
  isDestructive() → false          （需显式声明）
  shouldAvoidPermissionPrompts → 后台 Agent 不弹 UI
```

每个 Tool 必须**主动证明**自己是安全的，而不是默认信任。

**安全层级**:
```
组织策略 (不可绕过)
  ↓
权限规则 (deny > allow > ask)
  ↓
权限模式 (plan/default/auto/bypass)
  ↓
Tool 级别检查 (checkPermissions)
  ↓
用户确认 (权限对话框)
```

---

## 2. 不可变上下文 (Immutable Context)

`ToolPermissionContext` 使用 `DeepImmutable` 标记。Tool 不能直接修改执行上下文：

```typescript
type ToolPermissionContext = DeepImmutable<{
  mode: PermissionMode
  alwaysAllowRules: ToolPermissionRulesBySource
  // ...
}>
```

需要修改上下文时，通过 `contextModifier` 返回新的上下文：

```typescript
type ToolResult<T> = {
  data: T
  contextModifier?: (context: ToolUseContext) => ToolUseContext
  // contextModifier 只在非并发安全的 Tool 上生效
}
```

---

## 3. 延迟加载与编译时消除

### 动态 import

```typescript
// 而不是顶层 import
const { someModule } = await import('./heavy-module.js')
```

### Feature Flags 死代码消除

```typescript
import { feature } from 'bun:bundle'

// 编译时：如果 VOICE_MODE 为 false，require 和整个 if 块被完全移除
const voiceModule = feature('VOICE_MODE')
  ? require('./voice/index.js')
  : null
```

### 懒加载 require（打破循环依赖）

```typescript
// 不在顶层 import，而是在使用时才 require
const getTeamCreateTool = () =>
  require('./tools/TeamCreateTool/TeamCreateTool.js').TeamCreateTool
```

---

## 4. Schema 驱动 (Schema-Driven)

所有外部输入都通过 Zod schema 校验：

| 对象 | Schema |
|------|--------|
| Tool 输入 | `inputSchema: z.ZodType` |
| Tool 输出 | `outputSchema: z.ZodType` |
| 配置文件 | settings schema |
| Hook 定义 | hook schema |
| MCP 消息 | MCP protocol schema |

好处：
- 运行时类型安全
- 自动生成 JSON Schema（给模型描述 Tool 参数）
- 校验错误消息清晰

---

## 5. 可观察性 (Observability)

### 多层日志

```typescript
logForDebugging(...)          // 调试日志
logForDiagnosticsNoPII(...)   // 诊断日志（不含个人信息）
logEvent(...)                 // 分析事件
logError(...)                 // 错误日志
logAntError(...)              // Anthropic 内部错误
```

### 启动分析

```typescript
profileCheckpoint('init_function_start')
profileCheckpoint('init_configs_enabled')
profileCheckpoint('init_network_configured')
// 精确追踪每个初始化阶段耗时
```

### 费用追踪

```typescript
accumulateUsage(usage)
const cost = getTotalCost()
const model = getModelUsage()
```

---

## 6. 优雅降级 (Graceful Degradation)

```
API 失败 → 重试 → 降级到备用模型
MCP 连接失败 → 继续工作，仅缺少 MCP Tool
LSP 启动失败 → 继续工作，仅缺少代码智能
远程设置加载失败 → 使用本地默认值
Hook 执行超时 → 继续，不阻塞主流程
```

每个外部依赖的失败都不会导致整个应用崩溃。

---

## 7. 渐进式能力发现 (Progressive Capability)

### ToolSearch 延迟加载

不是所有 40+ Tool 都立即暴露给模型：

```typescript
// Tool 可以标记为延迟加载
readonly shouldDefer?: boolean    // 需通过 ToolSearch 发现
readonly alwaysLoad?: boolean     // 始终加载
```

模型先看到核心 Tool，通过 `ToolSearchTool` 按需发现更多 Tool。这减少了初始 prompt 大小。

### 技能发现

类似地，技能也是按需发现的：

```typescript
discoveredSkillNames?: Set<string>  // 已发现的技能
```

---

## 8. 进程隔离 (Process Isolation)

| 机制 | 说明 |
|------|------|
| **Git Worktree** | 文件系统级隔离 |
| **子 Agent** | 消息历史隔离 |
| **后台任务** | 独立进程，不弹 UI |
| **MCP 服务器** | 独立进程，通过 stdio/SSE 通信 |
| **Hook 命令** | 独立 Shell 进程 |

---

## 9. Bridge 模式 (双向桥接)

IDE 集成不是简单的插件调用，而是完整的双向桥接：

```
CLI (Claude Code)  ←──WebSocket──→  IDE Extension (VS Code/JetBrains)
  │                                    │
  ├── 会话管理                          ├── UI 展示
  ├── Tool 执行                        ├── 编辑器集成
  ├── 权限检查                          ├── 权限回调
  └── 状态同步                          └── 诊断信息
```

Bridge 使用 JWT 认证，轮询发现会话。

---

## 10. 状态管理：类 Zustand 模式

```typescript
// state/AppState.ts
type AppState = {
  // 全局应用状态
}

// 类似 Zustand 的 selector 订阅
getAppState(): AppState
setAppState(f: (prev: AppState) => AppState): void
```

使用 `Object.is` 进行变更检测，只在状态真正变化时触发更新。

---

## 总结：Claude Code 的设计哲学

```
1. 安全是底线 → 失败关闭、权限分层、不可变上下文
2. 性能是追求 → 延迟加载、编译时消除、预连接
3. 可靠性是基础 → 优雅降级、重试机制、清理回调
4. 可扩展是目标 → 插件/技能/MCP/Hook 四层扩展
5. 可观察是保障 → 多层日志、费用追踪、启动分析
```

> 这套架构体现了一个成熟的生产级 AI Agent 系统的工程实践——不仅要让 AI 能做事，更要让它**安全地、可控地、可观察地**做事。